---
layout: api
page_title: ACL Binding Rules - HTTP API
description: The /acl/binding-rules endpoints are used to configure and manage ACL binding rules.
---

# ACL Binding Rules HTTP API

The `/acl/binding-rules` and `/acl/binding-rule` endpoints are used to manage ACL Binding Rules.

## Read Binding Rule by Name

This endpoint reads an ACL Binding Rule with the given name. This queries the
Binding Rule that has been replicated to the region, and may lag behind the
authoritative region.

| Method | Path                            | Produces           |
| ------ | ------------------------------- | ------------------ |
| `GET`  | `/v1/acl/binding-rule/:rule_id` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries),
[consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------ |
| `YES`            | `all`             | `management` |

### Parameters

- `:rule_id` `(string: <required>)` - Specifies the ID of the ACL Binding Rule.
  This is specified as part of the path.

### Sample Request

```shell-session
$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/binding-rule/5da76548-1a60-b8fb-f9be-c7736a5bca09
```

### Sample Response

```json
{
  "AuthMethod": "example-acl-auth-method",
  "BindName": "role",
  "BindType": "role",
  "CreateIndex": 16,
  "CreateTime": "2022-12-16T10:29:07.248465Z",
  "Description": "updated-acl-binding-rule",
  "ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09",
  "ModifyIndex": 17,
  "ModifyTime": "2022-12-19T16:40:52.602004Z",
  "Selector": "engineering in list.roles"
}
```

## List Binding Rules

This endpoint lists all ACL Binding Rules. This lists the Binding Rules that have
been replicated to the region, and may lag behind the authoritative region.

| Method | Path                    | Produces           |
| ------ | ----------------------- | ------------------ |
| `GET`  | `/v1/acl/binding-rules` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries),
[consistency modes](/nomad/api-docs#consistency-modes) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | Consistency Modes | ACL Required                                                                                                                             |
| ---------------- | ----------------- | ------------ |
| `YES`            | `all`             | `management` |

### Sample Request

```shell-session
$ curl \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/binding-rules
```

### Sample Response

```json
[
  {
    "AuthMethod": "auth0",
    "CreateIndex": 16,
    "Description": "updated-acl-binding-rule",
    "Hash": "N7aEMsAfl3btWrZSwaWdzcRIAO3uRrRH2yQ8rPsuJ44=",
    "ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09",
    "ModifyIndex": 17
  }
]
```

## Create Binding Rule

This endpoint creates an ACL Binding Rule. The request is always forwarded to the
authoritative region.

| Method | Path                   | Produces           |
| ------ | ---------------------- | ------------------ |
| `POST` | `/v1/acl/binding-rule` | `application/json` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO`             | `management` |

### Parameters

- `Description` `(string: "")` - Human-readable, operator set description that
  can provide additional context about the binding role. This is an operational
  field.

- `AuthMethod` `(string: <required>)` - Name of the auth method for which this
  rule applies to. This is a required field and the method must exist within state
  before the cluster administrator can create the rule.

- `Selector` `(string: "")` - A boolean expression that matches against verified
  identity attributes returned from the auth method during login.  This is
  optional and when not set, provides a catch-all rule. If set, it must be a
  valid [go-bexpr][] expression; for example, a dash in the claim name will
  require it to be encased in quotes and escaped such as
  `"\"project-developer\" in list.roles"`.

  ~> **Caveat:** Selectors that operate on `ClaimMappings` (as opposed to
  `ListClaimMappings`), the key that we match against has to be prefixed with
  `value.` (e.g. `value.owner == username` for a claim mapping that has `owner`
  as its key).

- `BindType` `(string: <required>)` - Adjusts how this binding rule is applied
  at login time. Valid values are `role`, `policy`, and `management`.

- `BindName` `(string: <required>)` - Target of the binding. Can be lightly
  templated using HIL ${foo} syntax from available field names. If the bind
  type is set to `management`, this should not be set. How it is used depends
  on the BindType.

### Sample Payload

```json
{
  "Description": "example-acl-binding-rule",
  "AuthMethod": "auth0",
  "Selector": "engineering in list.roles",
  "BindType": "role",
  "BindName": "eng-ro",
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    --data @payload.json \
    https://localhost:4646/v1/acl/binding-rule
```

### Sample Response

```json
{
  "AuthMethod": "auth0",
  "BindName": "eng-ro",
  "BindType": "role",
  "CreateIndex": 16,
  "CreateTime": "2022-12-16T10:29:07.248465Z",
  "Description": "example-acl-binding-rule",
  "ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09",
  "ModifyIndex": 16,
  "ModifyTime": "2022-12-16T10:29:07.248465Z",
  "Selector": "engineering in list.roles"
}
```

## Update Binding Rule

This endpoint updates an existing ACL Binding Rule. The request is always
forwarded to the authoritative region.

| Method | Path                            | Produces           |
| ------ | ------------------------------- | ------------------ |
| `POST` | `/v1/acl/binding-rule/:rule_id` | `application/json` |

The table below shows this endpoint's support for [blocking
queries](/nomad/api-docs#blocking-queries) and [required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO`             | `management` |

### Parameters

- `Description` `(string: "")` - Human-readable, operator set description that
  can provide additional context about the binding role. This is an operational
  field.

- `Selector` `(string: "")` - A boolean expression that matches against verified
  identity attributes returned from the auth method during login.  This is
  optional and when not set, provides a catch-all rule. If set, it must be a
  valid [go-bexpr][] expression; for example, a dash in the claim name will
  require it to be encased in quotes and escaped such as
  `"\"project-developer\" in list.roles"`.

- `BindType` `(string: "")` - Adjusts how this binding rule is applied at login
  time. Valid values are `role`, `policy`, and `management`.

- `BindName` `(string: "")` - Target of the binding. Can be lightly templated
  using HIL ${foo} syntax from available field names. How it is used depends on
  the BindType.

### Sample Payload

```json
{
  "Description": "new description",
}
```

### Sample Request

```shell-session
$ curl \
    --request POST \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    --data @payload.json \
    https://localhost:4646/v1/acl/binding-rule/example-acl-binding-rule
```

### Sample Response

```json
{
  "AuthMethod": "auth0",
  "BindName": "eng-ro",
  "BindType": "role",
  "CreateIndex": 16,
  "CreateTime": "2022-12-16T10:29:07.248465Z",
  "Description": "new description",
  "ID": "5da76548-1a60-b8fb-f9be-c7736a5bca09",
  "ModifyIndex": 17,
  "ModifyTime": "2022-12-19T16:40:52.602004Z",
  "Selector":"engineering in list.roles"
}
```

## Delete Binding Rule

This endpoint deletes the ACL Binding Rule as identified by its ID. This request
is always forwarded to the authoritative region.

| Method   | Path                            | Produces       |
| -------- | ------------------------------- | -------------- |
| `DELETE` | `/v1/acl/binding-rule/:rule_id` | `(empty body)` |

The table below shows this endpoint's support for
[blocking queries](/nomad/api-docs#blocking-queries) and
[required ACLs](/nomad/api-docs#acls).

| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO`             | `management` |

### Parameters

- `rule_id` `(string: <required>)` - Specifies the ID of Binding Rule to delete
  and is specified as part of the path.

### Sample Request

```shell-session
$ curl \
    --request DELETE \
    --header "X-Nomad-Token: <NOMAD_TOKEN_SECRET_ID>" \
    https://localhost:4646/v1/acl/binding-rule/5da76548-1a60-b8fb-f9be-c7736a5bca09
```

[go-bexpr]: https://github.com/hashicorp/go-bexpr
